home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d18 / docit.arc / DOCIT.DOC next >
Text File  |  1991-04-28  |  13KB  |  344 lines
  1. DOCIT V1.11 File docit                   Date Dec 20 1989 04:40   Page : 1
  2.  
  3. 1 DOCIT - INTRODUCTION ...................................................... 1
  4.    1.1 Purpose of program ................................................... 1
  5.    1.2 How to use program ................................................... 1
  6. 2 COMMAND LINE SWITCHES ..................................................... 2
  7.    2.1  Short summary ....................................................... 2
  8.    2.2  Long summary ........................................................ 3
  9. 3 EMBEDDED COMMANDS ......................................................... 4
  10.    3.1 table of commands .................................................... 4
  11.    3.2 doc-on, doc-off, page break .......................................... 4
  12.    3.3 include file ......................................................... 4
  13.    3.4 table of contents entry .............................................. 5
  14. 4 EXAMPLES .................................................................. 6
  15.    4.1 embedded command ..................................................... 6
  16.    4.2 filelist ............................................................. 7
  17. 5 LICENSE & DISCLAIMER ...................................................... 8
  18. DOCIT V1.11 File docit.lst               Date Dec 20 1989 04:40   Page : 1
  19.  
  20.  
  21.  DOCIT was designed to quickly generate a hardcopy of function headers for 
  22. easy reference. With DOCIT you can avoid having to maintain both the
  23. source file and a summary file. While the summary is convenient for finding
  24. a required function and it's arguments without showing source, it is often
  25. overlooked when modifications are done or new functions added.
  26.  
  27.  DOCIT redirects the header and any other pertinent information
  28. from the source code itself into a file to be printed. DOCIT will also
  29. generate a table of contents to quickly find the desired function. Now
  30. there is no need to wade through hundreds of pages of source looking for
  31. the right function. Simply go down the list of functions in the table
  32. of contents, and then turn to the correct page. And the information
  33. will be accurate since this IS the header for the function, not just
  34. poorly maintained copy of the header.
  35.  
  36.  DOCIT works by searching for commands embedded in comments throughout
  37. source code. Commands such as document on, document off, page break,
  38. table of contents entry and include file (for copyright notices etc).
  39. Using a text file with a list of source files stored in it, DOCIT can
  40. generate a function library users manual in minutes. And DOCIT will support
  41. C, Pascal, Basic, Assemble and text files.
  42.  
  43.  
  44.  
  45.  The following steps will get you on your way to having a neat professional
  46. library reference manual in no time.
  47.  
  48.          1) Learn the basic DOCIT commands (doc on, doc off, page break
  49.             include file, table of contents entry). See the section on 
  50.             commands for a complete explanations.
  51.  
  52.          2) Add the DOCIT commands to your function headers, and anywhere
  53.             that you want to have notes (or source) show up in your
  54.             reference manual. In most cases, the commands will consist of
  55.             turning the document mode on at the top of the function header
  56.             turning it off at the bottom of the header, and putting in
  57.             a table of contents marker.
  58.  
  59.          3) Create a file with a list of all source code files (including
  60.             full path name). See the section on filelists an example.
  61.  
  62.          4) Run DOCIT. On your initial run, be sure to watch the DOCIT screen
  63.             output for warnings. For example, if you forgot to turn document
  64.             mode off, then DOCIT will tell you.
  65.  
  66.          5) Print out the table of contents and the document listing.
  67.  
  68. DOCIT V1.11 File docit.lst               Date Dec 20 1989 04:40   Page : 2
  69.  
  70. Extract documentation from source files for listings
  71.  
  72. Usage : DOCIT -lfile [-ofile][-ipath][-ipath][-pnn][-v][-w][-t][-h]
  73.  
  74.         -l : filelist filename             -o : output filename
  75.         -p : lines/page                    -t : no table of contents
  76.         -w : warnings off                  -v : verbose off
  77.         -i : include path search list
  78.  
  79.         -h : INTERACTIVE HELP - description, use and examples
  80.  
  81.  If you find DOCIT useful, a contribution of $15.00 would be appreciated.
  82.   With a contribution of $25.00 or more you will be registered to receive a
  83.   disk with the next version of DOCIT when it is released. Please state the
  84.   current version of software that you have. Send contributions and any
  85.   suggestions for improving the program to :
  86.                                                 J. Allamby
  87.                                                 P.O. Box 435,
  88.                                                 Pickering,
  89.                                                 Ontario, Canada
  90.                                                 L1V 1C0
  91. DOCIT V1.11 File docit.lst               Date Dec 20 1989 04:40   Page : 3
  92.  
  93. List of command line switches
  94. -l  list filename   - DOCIT requires a file with a list of all files to be
  95.                       scanned. If no extension is given, then ".DML" is 
  96.                       used.
  97.  
  98. -t  no index        - The user can request that no table of contents be
  99.                       generated.
  100.  
  101. -o  output filename - By default, DOCIT will use the same filename as the
  102.                       list file with the extension ".OUT". The user can
  103.                       override that with a new name
  104.  
  105. -w  warnings off    - By default, DOCIT will warn the user if it found an
  106.                       unmatched doc on/off command, if it could not open
  107.                       an include file, or if the syntax was incorrect for
  108.                       either the include file command or the table of
  109.                       contents. The -w message will suppress these messages
  110.  
  111.  
  112.  
  113. List of command line switches (continued)
  114. -v verbose off      - By default, DOCIT will provide a summary for each file
  115.                       as it is processed. The user can suppress this by using
  116.                       the -v command.
  117.  
  118. -p lines/page       - By default, the number of lines per page is 65. The 
  119.                       user can specify the number of lines per page to suit.
  120.  
  121. -i include path     - The user can specify the -i command as many times as
  122.                       required to list all search paths for include files.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137. DOCIT V1.11 File docit.lst               Date Dec 20 1989 04:40   Page : 4
  138.  
  139.  The following table lists the commands available and their form
  140.  within each type of language specified
  141.  
  142. FILE_TYPE    DOC ON    DOC OFF    PAGE BREAK    INCLUDE FILE    TOC ENTRY
  143. .c        /*+d*/    /*-d*/    /*+p*/        /*+i"file"*/    /*+s0"string"*/
  144. .asm        ;;+d;;    ;;-d;;    ;;+p;;        ;;+i"file";;    ;;+s0"string";;
  145. .pas        {*+d*}    {*-d*}    {*+p*}        {*+i"file"*}    {*+s0"string"*}
  146. .bas        REM +d    REM -d    REM +p        REM +i"file"    REM +s0"string"
  147.  
  148.  
  149. IMPORTANT - Please note that the all commands are
  150.   in lowercase.
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161. DOCIT Embedded command list
  162. DOC ON         This command will direct all proceeding text to the output file.
  163.                DOCIT does not support multiple levels of document on.
  164.                If DOCIT encounters a DOC ON command when document is already
  165.                on, then a warning will be issued.
  166.  
  167.                Example : /*+d*/
  168.  
  169. DOC OFF        This command will stop directing text to the output file.
  170.                DOC ON and DOC OFF should be used in pairs. A warning will be
  171.                issued if a DOC OFF command is encountered when document mode
  172.                is already off. DOCIT will also display a warning if document
  173.                mode is still on at the end of a file (not an included file).
  174.  
  175.                Example : /*-d*/
  176.  
  177. PAGE BREAK     PAGE BREAK will start a new page on the output file. 
  178.  
  179.                Example : /*+p*/
  180.  
  181.  
  182.  
  183.  
  184.  
  185. DOCIT Embedded command list (continued)
  186. INCLUDE FILE   The INCLUDE FILE will begin reading text from file specified.
  187.                The user can specify the INCLUDE FILE command to a depth of 10
  188.                files. The state of the document mode (on/off) will be as set
  189.                by the file above the included file. In order to find include
  190.                files in different directories, DOCIT uses the -i command line
  191.                option to allow a user to enter 1 or more search paths. DOCIT
  192.                will search the current directory first.
  193.  
  194.                Example : /*+i"struct.h"*/
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201. DOCIT V1.11 File docit.lst               Date Dec 20 1989 04:40   Page : 5
  202.  
  203.  
  204.  
  205. DOCIT Embedded command list (continued)
  206. TOC ENTRY      The TOC ENTRY command allows the user to make additions
  207.                to the table of contents. Some examples of the command are :
  208.  
  209.                /*+s0"DATABASE ROUTINES"*/
  210.                /*+s1"DBSINT - Initialize database"*/
  211.                /*+s1"DBSTRM - Terminate database"*/
  212.                /*+s2"DBSSTA - Get stats"*/
  213.  
  214.                The TOC ENTRY command consists of two parts. The first
  215.                part is the section modifier, which is a single digit
  216.                proceeding the 's' identifier. The digit can be from 0 to 9
  217.                inclusive. The second part is the user provided string. Each
  218.                entry in the table of contents has associated with it a
  219.                section number and 0 or more sub-sections.
  220.                The examples given above will be saved in table of contents as
  221.  
  222.                1 DATABASE ROUTINES ..................................... 1
  223.                   1.1 DBSINT - Initialize database ..................... 1
  224.                   1.2 DBSTRM - Terminate database ...................... 1
  225.                     1.2.1 DBSSTA - Get stats ........................... 1
  226.  
  227. DOCIT Embedded command list (continued)
  228.  
  229.                Notice how the "s0" entry displays only the section value
  230.                and the first "s1" displays the section number plus one
  231.                sub-section value. A second "s1" will increment the sub-
  232.                section value by 1.
  233.                 DOCIT will automatically save the output listing page number
  234.                where the TOC entry was located.
  235.  
  236.                1 DATABASE ROUTINES ..................................... 1
  237.                   1.1 DBSINT - Initialize database ..................... 1
  238.                   1.2 DBSTRM - Terminate database ...................... 1
  239.                     1.2.1 DBSSTA - Get stats ........................... 1
  240.  
  241.  
  242.  
  243.  
  244.  
  245. DOCIT V1.11 File docit.lst               Date Dec 20 1989 04:40   Page : 6
  246.  
  247. The following is a sample of a function header formatted for use by DOCIT.
  248. It contains commands for both documenting and the table of contents.
  249.  
  250. /*+p*/
  251. /*+s0"STRLIB - String manipulation library"*/
  252. /*+s1"STRCMP - Compare 2 strings"*/
  253. /*+d*/
  254. /********************************************
  255. Function : strcmp
  256. Purpose  : Compare 2 strings 
  257. Call     : strcmp(s,t)
  258. Args
  259.       char *s,*t
  260. Return
  261.       < 0 if s < t, 0 if s = t, > 0 if s > t
  262. ********************************************/
  263. strcmp(s,t)
  264. char s[],t[];
  265. /*-d*/
  266. {
  267. body of function
  268. }
  269.  
  270. The preceeding example will produce the following entries in the table of
  271. contents
  272.  
  273. 1 STRLIB - Sting manipulation library ......................... 1
  274.    1.1 STRCMP - Compare 2 strings ............................. 1
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  The following is the output file produced by the header
  288.  
  289. DOCIT V1.08 File h:\lib\str\strlib.c        Date Nov 23 1989 Page : 1/1
  290. /********************************************
  291. Function : strcmp
  292. Purpose  : Compare 2 strings 
  293. Call     : strcmp(s,t)
  294. Args
  295.       char *s,*t
  296. Return
  297.       < 0 if s < t, 0 if s = t, > 0 if s > t
  298. ********************************************/
  299. strcmp(s,t)
  300. char s[],t[];
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308. DOCIT V1.11 File docit.lst               Date Dec 20 1989 04:40   Page : 7
  309.  
  310.  In order for DOCIT to search the required files, the user must provide
  311. a file with all source files explicitly listed, one per line in the file
  312. with the full path name. Since DOCIT determines the type of file given by
  313. the file extension, a mechanism has been added to allow other file
  314. extensions to be listed. Immediately after the filename, add the class of file
  315. that it belongs to. Valid classes are as follows
  316.  
  317.      .c   .pas   .bas   .asm (.s)   .txt
  318.  
  319. This is a sample filelist as expected by DOCIT
  320.  
  321. C:\LIB\SRC\DECODE.C
  322. C:\LIBSRC\LIBRTN.H     .C
  323. C:\PROJ1\HDWRTN.ASM
  324. DRIVER.C
  325. C:\PROJ1\EDITOR.PAS
  326. C:\PROJ2\EDIT.INC      .PAS
  327.  
  328.  
  329.  
  330.  
  331.  
  332. DOCIT V1.11 File docit.lst               Date Dec 20 1989 04:40   Page : 8
  333.  
  334. You are free to use, copy and distribute DOCIT for noncommercial use IF :
  335.  
  336. NO FEE IS CHARGED FOR USE, COPYING OR DISTRIBUTION,
  337. AND IT IS NOT MODIFIED IN ANY WAY.
  338.  
  339. This program is provided AS IS without any warranty, expressed or implied,
  340. including but not limited to fitness for a particular purpose.
  341.  
  342.  
  343.  
  344.